Skip to main content

Field Value JQL Function

This document describes the fieldValue JQL function that allows you to retrieve and compare values from specific fields in issues matching a query.

Overview​

The fieldValue JQL function enables you to extract and compare values from specific fields in issues that match a given query. This is particularly useful when you need to perform operations or comparisons on field values across multiple issues, especially when comparing values between different fields.

Available Function​

fieldValue(subQuery, field)​

Retrieves values from the specified field in issues matching the subquery.

Example:

"Story Points" > fieldValue("project = DEV", "estimate")

This query finds all issues where the Story Points value is higher than the estimate value of issues in the DEV project.

Usage Notes​

  1. The function requires two arguments:
    • A valid JQL subquery
    • The name of the field to retrieve values from
  2. The function supports multiple operators:
    • =, != (for exact matching)
    • >, >=, <, <= (for numerical comparisons)
    • in, not in (for list comparisons)
  3. Results are calculated based on the current values of the fields at the time of the query.

Syntax​

The general syntax for using the fieldValue function in JQL is:

field [operator] fieldValue("jql_subquery", "field_name")

Where:

  • field is the field to compare against
  • operator is one of: =, !=, >, >=, <, <=, in, not in
  • jql_subquery is a valid JQL query that returns a set of issues
  • field_name is the name of the field to retrieve values from

Field Types and Format Support​

Supported Field Types​

The fieldValue function works with various field types:

  • Text fields (Summary, Description)
  • Number fields
  • Date fields
  • User fields
  • Label fields
  • Custom fields of the above types

Custom Fields​

When using custom fields:

  • Always use the field's display name, not its ID
  • Example: Use "Story Points" instead of "customfield_10001"

Field Value Formatting​

  • Text fields: Exact string matching
  • Number fields: Numerical comparison
  • Date fields: Date comparison (supports various date formats)
  • User fields: Username or display name matching
  • Label fields: Label name matching

Examples​

Comparing Different Fields​

Find issues where Story Points are higher than the estimate:

"Story Points" > fieldValue("project = DEV", "estimate")

Find issues where the reporter is the same as the assignee:

reporter = fieldValue("project = DEV", "assignee")

Find issues where the fix version matches the affected version:

fixVersion in fieldValue("project = DEV", "affectedVersion")

Find issues where resolutionDate is greater than the duedate: resolutionDate > fieldValue("project = DEV", "dueDate")

Best Practices​

  1. Always provide a valid JQL subquery:

    • The subquery must be a valid JQL expression
    • The subquery should be specific enough to return a manageable set of issues

  2. Use appropriate field names:

    • Use the field's display name
    • Be aware of case sensitivity
    • For custom fields, use the configured display name

  3. Consider performance implications:

    • Complex subqueries may impact query performance
    • Very broad subqueries may slow down the search
    • Consider using more specific subqueries to limit the result set

  4. Combine with other JQL functions:

    • The fieldValue function can be combined with other JQL functions
    • Use parentheses to ensure proper operator precedence

Error Handling​

The function will return an error if:

  1. The specified field name is not valid
  2. The JQL subquery is invalid
  3. The field name is not found in the system
  4. The operator is not compatible with the field type
  5. The comparison value is not in the correct format for the field type

Performance Considerations​

  1. Field Type Impact:

    • Text field comparisons are generally faster than complex field types
    • Date and number comparisons may require additional processing
    • User and label field comparisons may involve additional lookups

  2. Subquery Size:

    • Large subqueries may impact performance
    • Consider using more specific subqueries to limit the result set

  3. Result Set Size:

    • Large result sets may impact performance
    • Use appropriate subqueries to limit the number of issues to search through

  4. Field Value Size:

    • Large text fields may impact performance
    • Consider using more specific subqueries to limit the result set